.TH SG_SES "8" "June 2023" "sg3_utils\-1.48" SG3_UTILS
.SH NAME
sg_ses \- access a SCSI Enclosure Services (SES) device
.SH SYNOPSIS
.B sg_ses
[\fI\-\-all\fR] [\fI\-\-ALL\fR] [\fI\-\-descriptor=DES\fR]
[\fI\-\-dev\-slot\-num=SN\fR] [\fI\-\-eiioe=A_F\fR] [\fI\-\-filter\fR]
[\fI\-\-get=STR\fR] [\fI\-\-hex\fR] [\fI\-\-index=IIA\fR |
\fI\-\-index=TIA,II\fR] [\fI\-\-inner\-hex\fR] [\fI\-\-join\fR]
[\fI\-\-json[=JO]\fR] [\fI\-\-js\-file=JFN\fR] [\fI\-\-maxlen=LEN\fR]
[\fI\-\-no\-config\fR] [\fI\-\-no\-time\fR] [\fI\-\-page=PG\fR]
[\fI\-\-quiet\fR] [\fI\-\-raw\fR] [\fI\-\-readonly\fR]
[\fI\-\-sas\-addr=SA\fR] [\fI\-\-status\fR] [\fI\-\-verbose\fR]
[\fI\-\-warn\fR] \fIDEVICE\fR
.PP
.B sg_ses
\fI\-\-control\fR [\fI\-\-byte1=B1\fR] [\fI\-\-clear=STR\fR]
[\fI\-\-data=H,H...\fR] [\fI\-\-data=@FN\fR] [\fI\-\-descriptor=DES\fR]
[\fI\-\-dev\-slot\-num=SN\fR] [\fI\-\-index=IIA\fR | \fI\-\-index=TIA,II\fR]
[\fI\-\-mask\fR] [\fI\-\-maxlen=LEN\fR] [\fI\-\-nickname=SEN\fR]
[\fI\-\-nickid=SEID\fR]  [\fI\-\-page=PG\fR] [\fI\-\-readonly\fR]
[\fI\-\-sas\-addr=SA\fR] [\fI\-\-set=STR\fR] [\fI\-\-verbose\fR]
\fIDEVICE\fR
.PP
.B sg_ses
\fI\-\-data=@FN\fR \fI\-\-status\fR [\fI\-\-raw\fR \fI\-\-raw\fR]
[<all options from first form>]
.br
.B sg_ses
\fI\-\-inhex=FN\fR \fI\-\-status\fR [\fI\-\-raw\fR \fI\-\-raw\fR]
[<all options from first form>]
.PP
.B sg_ses
[\fI\-\-enumerate\fR] [\fI\-\-index=IIA\fR] [\fI\-\-list\fR] [\fI\-\-help\fR]
[\fI\-\-version\fR]
.SH DESCRIPTION
.\" Add any additional description here
Fetches management information from a SCSI Enclosure Service (SES) device.
This utility can also modify the state of a SES device. The \fIDEVICE\fR
should be a SES device which may be a dedicated enclosure services processor
in which case an INQUIRY response's Peripheral Device Type is 13 [0xd].
Alternatively it may be attached to another type of SCSI device (e.g. a
disk) in which case the EncServ bit is set in its INQUIRY response.
.PP
If the \fIDEVICE\fR argument is given with no options then the names of all
SES diagnostic pages (dpages) supported are listed. Most of the named dpages
are defined in the SES standards and drafts. The most recent reference for
this utility is the draft SCSI Enclosure Services 4 document T10/BSR INCITS
555 Revision 5 at https://www.t10.org . Existing standards for SES, SES\-2
and SES\-3 are ANSI INCITS 305\-1998 and ANSI INCITS 448\-2008 and ANSI
INCITS 518\-2017 respectively.
.PP
SAS expanders typically have a SES device attached via a virtual port. Some
HBAs (SCSI initiators) choose to expose a SES device internally. That means
the SCSI subsystem on the host machine can see the SES device, but devices
connected to that HBA (e.g. a SAS expander) cannot see the HBA's SES device.
That internal SES device might report on the temperature(s) of the HBA and
whether anything is connected to its SCSI ports.
.PP
The first form shown in the SYNOPSIS is for fetching and decoding dpages or
fields from the SES \fIDEVICE\fR. A SCSI RECEIVE DIAGNOSTIC RESULTS command
is sent to the \fIDEVICE\fR to obtain each dpage response.  Rather than
decoding a fetched dpage, its contents may be output in hex or binary with
the \fI\-\-hex\fR or \fI\-\-raw \-\-raw\fR options.
.PP
The second form in the SYNOPSIS is for modifying dpages or fields held in the
SES \fIDEVICE\fR. A SCSI SEND DIAGNOSTIC command containing a "control" dpage
is sent to the \fIDEVICE\fR to cause changes. Changing the state of an
enclosure (e.g. requesting the "ident" (locate) LED to flash on a disk tray
in an array) is typically done using a read\-modify\-write cycle. See the
section on CHANGING STATE below.
.PP
The third form in the SYNOPSIS has two equivalent invocations shown. They
decode the contents of a file (named \fIFN\fR) that holds a hexadecimal or
binary representation of one, or many, SES dpage responses. Typically an
earlier invocation of the first form of this utility with the '\-HHHH' option
would have generated that file. Since no SCSI commands are sent; the
\fIDEVICE\fR argument, if given, will be ignored.
.PP
The last form in the SYNOPSIS shows the options for providing command line
help (i.e. usage information), listing out dpage and field information tables
held by the utility (\fI\-\-enumerate\fR), or printing the version string
of this utility.
.PP
There is a web page discussing this utility at
https://sg.danny.cz/sg/sg_ses.html . Support for downloading microcode to
a SES device has been placed in a separate utility called sg_ses_microcode.
.PP
In the following sections "dpage" refers to a diagnostic page, either fetched
with a SCSI RECEIVE DIAGNOSTIC RESULTS command, sent to the \fIDEVICE\fR with
a SCSI SEND DIAGNOSTIC command, or fetched from data supplied by the
\fI\-\-data=\fR or the \fI\-\-inhex=FN\fR option.
.SH OPTIONS
Arguments to long options are mandatory for short options as well.
The options are arranged in alphabetical order based on the long option name.
.TP
\fB\-a\fR, \fB\-\-all\fR
shows the output of the \fI\-\-join\fR option followed by the other SES
dpages. Since a single \fI\-\-join\fR option does not include the Threshold
In dpage, it is listed separately in the "other SES dpages" section. In
this context, "other" means all SES dpages that have not (explicitly) been
output by the \fI\-\-join\fR option.
.br
To output all pages without attempting a join, use the \fI\-\-page=all\fR
option rather than this option.
.br
If this option is used twice, the Threshold In dpage (if available) is
included in the \fI\-\-join\fR option output. Note that now the Threshold In
dpage is not listed separately in the "other SES dpages" section. Using this
option twice is equivalent to invoking the \fI\-\-ALL\fR option.
.br
This option implies the \fI\-\-status\fR option as long as the
\fI\-\-control\fR option has not been given.
.br
Using this option together with the \fI\-HHH\fR, \fI\-HHHH\fR or
\fI\-HHHHH\fR options is considered an error as it produces confusing output.
To force the issue use \fI\-H\fR times (as discouragement). Instead using the
\fI\-\-page=all\fR option together with the \fI\-HHH\fR, \fI\-HHHH\fR or
\fI\-HHHHH\fR options will more likely produce the desired output: a dump of
all SES diagnostics pages in hex suitable for later parsing or visual
inspection with a text editor.
.TP
\fB\-z\fR, \fB\-\-ALL\fR
shows the output of the \fI\-\-join\fR option invoked twice, followed by the
other SES dpages. Since two \fI\-\-join\fR options does include the Threshold
In dpage, that dpage is not listed separately in the "other SES dpages"
section.
.br
This option implies the \fI\-\-status\fR option as long as the
\fI\-\-control\fR option has not been given.
.TP
\fB\-b\fR, \fB\-\-byte1\fR=\fIB1\fR
some modifiable dpages may need byte 1 (i.e. the second byte) set. In the
Enclosure Control dpage, byte 1 contains the INFO, NON\-CRIT, CRIT and
UNRECOV bits. In the Subenclosure String Out, Subenclosure Nickname Control
and Download Microcode Control dpages, byte 1 is the Subenclosure identifier.
Active when the \fI\-\-control\fR and \fI\-\-data=H,H...\fR options are used
and the default value is 0. If the \fI\-\-clear=STR\fR or \fI\-\-set=STR\fR
option is used then the value read from byte 1 is written back to byte 1.
\fIB1\fR is in decimal unless it is prefixed by '0x' or '0X' (or has a
trailing 'h' or 'H').
.TP
\fB\-C\fR, \fB\-\-clear\fR=\fISTR\fR
Used to clear an element field in the Enclosure Control or Threshold Out
dpage. Must be used together with an indexing option to specify which element
is to be changed. The Enclosure Control dpage is assumed if the
\fI\-\-page=PG\fR option is not given. See the STR FORMAT and the CLEAR, GET,
SET sections below.
.TP
\fB\-c\fR, \fB\-\-control\fR
will send control information to the \fIDEVICE\fR via a SCSI SEND
DIAGNOSTIC command. Cannot give both this option and \fI\-\-status\fR.
The Enclosure Control, String Out, Threshold Out, Array Control (obsolete
in SES\-2), Subenclosure String Out, Subenclosure Nickname Control and
Download Microcode dpages can be set currently. This option is assumed if
either the \fI\-\-clear=STR\fR or \fI\-\-set=STR\fR option is given.
.TP
\fB\-d\fR, \fB\-\-data\fR=\fIH,H...\fR
permits a string of comma separated (ASCII) hex bytes to be specified (limit
1024). A (single) space separated string of hex bytes is also allowed but
the list needs to be in quotes. This option allows the parameters to a
control dpage to be specified. The string given should not include the first 4
bytes (i.e. page code and length). See the DATA SUPPLIED section below.
.TP
\fB\-d\fR, \fB\-\-data\fR=\-
reads one or more data strings from stdin, limit almost 2**16 bytes. stdin
may provide ASCII hex as a comma separated list (i.e. as with the
\fI\-\-data=H,H...\fR option). Additionally spaces, tabs and line feeds are
permitted as separators from stdin . Stops reading stdin when an EOF is
detected. See the DATA SUPPLIED section below.
.TP
\fB\-d\fR, \fB\-\-data\fR=@\fIFN\fR
reads one or more data strings from the file called \fIFN\fR, limit almost
2**16 bytes. The contents of the file is decoded in the same fashion as
stdin described in the previous option. See the DATA SUPPLIED section below.
.TP
\fB\-D\fR, \fB\-\-descriptor\fR=\fIDES\fR
where \fIDES\fR is a descriptor name (string) as found in the Element
Descriptor dpage. This is a medium level indexing alternative to the low
level \fI\-\-index=\fR options. If the descriptor name contains a space then
\fIDES\fR needs to be surrounded by quotes (single or double) or the space
escaped (e.g. preceded by a backslash). See the DESCRIPTOR NAME, DEVICE SLOT
NUMBER AND SAS ADDRESS section below.
.TP
\fB\-x\fR, \fB\-\-dev\-slot\-num\fR=\fISN\fR, \fB\-\-dsn\fR=\fISN\fR
where \fISN\fR is a device slot number found in the Additional Element Status
dpage. Only entries for FCP and SAS devices (with EIP=1) have device slot
numbers. \fISN\fR must be a number in the range 0 to 255 (inclusive). 255 is
used to indicate there is no corresponding device slot. This is a medium level
indexing alternative to the low level \fI\-\-index=\fR options. See the
DESCRIPTOR NAME, DEVICE SLOT NUMBER AND SAS ADDRESS section below.
.TP
\fB\-E\fR, \fB\-\-eiioe\fR=\fIA_F\fR
\fIA_F\fR is either the string 'auto' or 'force'. There was some fuzziness
in the interpretation of the 'element index' field in the Additional Element
Status (AES) dpage between SES\-2 and SES\-3. The EIIOE bit was introduced to
resolve the problem but not all enclosures have caught up. In the SES\-3
revision 12 draft the EIIOE bit was expanded to a 2 bit EIIOE field.
Using '\-\-eiioe=force' will decode the AES dpage as if the EIIOE field is set
to 1.  Using '\-\-eiioe=auto' will decode the AES dpage as if the EIIOE field
is set to 1 if the first AES descriptor has its EIP bit set and its element
index field is 1 (in other words a heuristic to guess whether the EIIOE field
should be set to 1 or 0).
.br
If the enclosure sets the actual EIIOE field to 1 or more then this option has
no effect. It is recommended that HP JBOD users set \-\-eiioe=auto .
.TP
\fB\-e\fR, \fB\-\-enumerate\fR
enumerate all known diagnostic page (dpage) names and SES elements that this
utility recognizes plus the abbreviations accepted by this utility. Ignores
\fIDEVICE\fR if it is given. Essentially it is dumping out tables held
internally by this utility.
.br
If \fI\-\-enumerate\fR is given twice, then the recognized acronyms for the
\fI\-\-clear=STR\fR, \fI\-\-get=STR\fR and \fI\-\-set=STR\fR options are
listed. The utility exits after listing this information, so most other
options and \fIDEVICE\fR are ignored. Since there are many acronyms for
the Enclosure Control/Status dpage then the output can be further restricted
by giving the \fI\-\-index=IIA\fR option (e.g. "sg_ses \-ee \-I ts" to only
show the acronyms associated with the Enclosure Control/Status dpage's
Temperature Sensor Element Type).
.TP
\fB\-f\fR, \fB\-\-filter\fR
cuts down on the amount of output from the Enclosure Status dpage and the
Additional Element Status dpage. When this option is given, any line which
has all its binary flags cleared (i.e. 0) is filtered out (i.e.  ignored).
If a line has some other value on it (e.g. a temperature) then it is output.
When this option is used twice only elements associated with the "status=ok"
field (in the Enclosure status dpage) are output. The \fI\-\-filter\fR option
is useful for reducing the amount of output generated by the \fI\-\-join\fR
option.
.TP
\fB\-G\fR, \fB\-\-get\fR=\fISTR\fR
Used to read a field in a status element. Must be used together with a an
indexing option to specify which element is to be read. By default the
Enclosure Status dpage is read, the only other dpages that can be read are the
Threshold In and Additional Element Status dpages. If a value is found it is
output in decimal to stdout (by default) or in hexadecimal preceded by "0x"
if the \fI\-\-hex\fR option is also given. See the STR FORMAT and the CLEAR,
GET, SET sections below.
.TP
\fB\-h\fR, \fB\-\-help\fR
output the usage message then exit. Since there is a lot of information,
it is split into two pages. The most important is shown on the first page.
Use this option twice (e.g. '\-hh') to output the second page. Note: the
\fI\-\-enumerate\fR option might also be viewed as a help or usage type
option. And like this option it has a "given twice" form: '\-ee'.
.TP
\fB\-H\fR, \fB\-\-hex\fR
If the \fI\-\-get=STR\fR option is given then output the value found (if
any) in hexadecimal, with a leading "0x". Otherwise output the response
in hexadecimal; with a leading hex address/index at the start of each line.
If given twice an ASCII rendering is given to the right of each line. If
given three or more times, the hexadecimal bytes only are output, 16
bytes (or less) on each line.
.br
Ignored when all elements from several dpages are being accessed (e.g. when
the \fI\-\-join\fR option is used). Also see the \fI\-\-raw\fR option which
may be used with this option.
.br
To dump one of more dpage responses to stdout in ASCII parsable hexadecimal
use \fI\-HHH\fR or \fI\-HHHH\fR. The triple H form only outputs hexadecimal
which is fine for a single dpage response. When all dpages are dumped (e.g.
with \fI\-\-page=all\fR) then the quad H form adds the name of each dpage
preceded by a hash mark ('#'). Hence the output of the quad H form is still
parsable plus it is easier for users to view and possibly edit. Using this
option 5 times (e.g. \fI\-HHHHH\fR) adds the page code in hex after the
page's name in the comment before the hex rendering of that mode page.
.br
If the \fI\-\-inner\-hex\fR option is also given it changes the action of
this option. See the description of the \fI\-\-inner\-hex\fR option. Giving
both \fI\-HHHH\fR (or greater) and the \fI\-\-inner\-hex\fR option is
reported as an error.
.br
Note that the meaning of '-H' and '-HH' have been swapped in
version "2.72 20230130" for compatibility with other utilities in this
package and the description of this option in the sg3_utils(8) manpage.
.TP
\fB\-I\fR, \fB\-\-index\fR=\fIIIA\fR
where \fIIIA\fR is either an individual index (II) or an Element type
abbreviation (A). See the INDEXES section below. If the \fI\-\-page=PG\fR
option is not given then the Enclosure Status (or Control) dpage is assumed.
May be used with the \fI\-\-join\fR option or one of the \fI\-\-clear=STR\fR,
\fI\-\-get=STR\fR or \fI\-\-set=STR\fR options. To enumerate the available
Element type abbreviations use the \fI\-\-enumerate\fR option.
.TP
\fB\-I\fR, \fB\-\-index\fR=\fITIA,II\fR
where \fITIA,II\fR is an type header index (TI) or Element type
abbreviation (A) followed by an individual index (II). See the INDEXES section
below. If the \fI\-\-page=PG\fR option is not given then the Enclosure
Status (or Control) dpage is assumed. May be used with the \fI\-\-join\fR
option or one of the \fI\-\-clear=STR\fR, \fI\-\-get=STR\fR or
\fI\-\-set=STR\fR options. To enumerate the available Element type
abbreviations use the \fI\-\-enumerate\fR option.
.TP
\fB\-X\fR, \fB\-\-inhex\fR=\fIFN\fR
where \fIFN\fR is a filename. It has the equivalent action of the
\fI\-\-data=@FN\fR option. If \fIFN\fR is '\-' then stdin is read. This
option has been given for compatibility with other utilities in this
package that use \fI\-\-inhex=FN\fR (or \fI\-\-in=FN\fR) is a similar
way. See the "HEX, BINARY AND JSON FORMATS" section in the
sg3_utils manpage for more information.
.TP
\fB\-i\fR, \fB\-\-inner\-hex\fR
the outer levels of a status dpage are decoded and printed out but the
innermost level(s) (e.g. the Element Status Descriptor) is output in hex.
For dpages that depend on the Configuration dpage, its structure is taken
into account with this option, while when the \fI\-\-no\-config\fR option
is used, its structure is ignored. Can be used with an indexing option
and/or \fI\-\-join\fR options. This option is mainly for debugging.
.br
This option may also be used with the \fI\-\-json[=JO]\fR option to lessen
the decoding dependency on other dpages. This option may be used twice in
this context. See the JSON INFORMATION section below.
.br
The \fI\-\-hex\fR option may be given with this option to control whether
ASCII appears to the right of each hex line of bytes, or not. Without a
\fI\-\-hex\fR option, ASCII appears to the right of each hex line of bytes;
if the \fI\-\-hex\fR option appear once, no ASCII rendering appears.
.TP
\fB\-j\fR, \fB\-\-join\fR
group elements from the Element Descriptor, Enclosure Status and Additional
Element Status dpages. If this option is given twice then elements from the
Threshold In dpage are also grouped. The order is dictated by the Configuration
dpage but that dpage is not explicitly shown.
.br
There can be a bewildering amount of information in the "join" output. The
default is to output everything. Several additional options are provided to
cut down the amount displayed. If the indexing options is given, only the
matching elements and their associated fields are output. The \fI\-\-filter\fR
option (see its description) can be added to reduce the amount of output.
Also "\-\-page=aes" (or "\-p 0xa") can be added to suppress the output of
rows that don't have a "aes" dpage component. See the INDEXES and DESCRIPTOR
NAME, DEVICE SLOT NUMBER AND SAS ADDRESS sections below.
.br
This option implies the \fI\-\-status\fR option. Giving the \fI\-\-control\fR
option with this option is an error.
.TP
\fB\-J\fR[=\fIJO\fR], \fB\-\-json\fR[=\fIJO\fR]
output is in JSON format instead of plain text form. Note that arguments
to the short and long form are themselves optional and if present start
with "=" and no whitespace is permitted around that "=".
.br
See sg3_utils_json manpage or use '?' for \fIJO\fR to get a summary.
For more specific information about JSON output with this utility, see the
JSON INFORMATION section below.
.TP
\fB\-Q\fR, \fB\-\-js\-file\fR=\fIJFN\fR
output is in JSON format and it is sent to a file named \fIJFN\fR. If that
file exists then it is truncated. By default, the JSON output is sent to
stdout.
.br
When this option is given, the \fI\-\-json[=JO]\fR option is implied and
need not be given. The \fI\-\-json[=JO]\fR option may still be needed to
set the \fIJO\fR parameter to non-default values.
.TP
\fB\-l\fR, \fB\-\-list\fR
This option is equivalent to \fI\-\-enumerate\fR. See that option.
.TP
\fB\-M\fR, \fB\-\-mask\fR
When modifying elements, the default action is a read (status element),
mask, modify (based on \fI\-\-clear=STR\fR or \fI\-\-set=STR\fR) then write
back as the control element. The mask step is new in sg_ses version 1.98
and is based on what is allowable (and in the same location) in draft SES\-3
revision 6. Those masks may evolve, as they have in the past. This option
re\-instates the previous logic which was to ignore the mask step. The
default action (i.e. without this option) is to perform the mask step in
the read\-mask\-modify\-write sequence.
.TP
\fB\-m\fR, \fB\-\-maxlen\fR=\fILEN\fR
\fILEN\fR is placed in the ALLOCATION LENGTH field of the SCSI RECEIVE
DIAGNOSTIC RESULTS commands sent by the utility. It represents the maximum
size of data the SES device can return (in bytes). It cannot exceed 65535
and defaults to 65532 (bytes). Some systems may not permit such large sizes
hence the need for this option. If \fILEN\fR is less than 0 or greater than
65535 then an error is generated. If \fILEN\fR is 0 then the default value
is used, otherwise if it is less than 4 then it is ignored (and a warning is
sent to stderr).
.TP
\fB\-n\fR, \fB\-\-nickname\fR=\fISEN\fR
where \fISEN\fR is the new Subenclosure Nickname. Only the first 32
characters (bytes) of \fISEN\fR are used, if more are given they are
ignored. See the SETTING SUBENCLOSURE NICKNAME section below.
.TP
\fB\-N\fR, \fB\-\-nickid\fR=\fISEID\fR
where \fISEID\fR is the Subenclosure identifier that the new
Nickname (\fISEN\fR) will be applied to. So \fISEID\fR must be an existing
Subenclosure identifier. The default value is 0 which is the
main enclosure.
.TP
\fB\-F\fR, \fB\-\-no\-config\fR
the Element status, Array status (obsolete), Element Descriptor, Additional
element status and Threshold In dpages all depend on the Configuration dpage
for decoding. For debugging purposes, when there is something wrong with the
relationship between these dpages, it may be useful to look at those pages
without using the configuration dpage. That is what this option does. Those
dpages still have some structure that can be output without the Configuration
dpage, but the inner parts are typically output in hex when this option is
given. This option is somewhat related to the \fI\-\-inner\-hex\fR option
which is also useful for debugging.
.br
This option is ignored on dpages that don't depend on the Configuration
dpage, including the Configuration dpage itself.
.TP
\fB\-y\fR, \fB\-\-no\-time\fR
this utility now issues a SCSI REPORT TIMESTAMP command just after an INQUIRY
command at the start of its execution. This enables the utility to output a
date\-time stamp or an uptime duration. The time value returned is in
illiseconds from some epoch. If the value corresponds to a period of less
than 3 years then it is considered to be an uptime duration and is output in
days, hours, minutes, seconds and milliseconds. Unix systems including Linux,
FreeBSD and Solaris use 00:00 on 1st January 1970 UTC as their epoch. The
date\-time stamp output is in RFC 2822 date format on two adjacent lines,
one in UTC and the other in local time.
.br
If for some reason calling the REPORT TIMESTAMP command causes a problem,
then this option will disable this feature.
.br
Note that the time returned is from the enclosure, not the machine that the
utility is executed from. This utility can use modern SCSI disks as the
\fIDEVICE\fR to fetch that disk't timestamp; this utility will then find
thet the \fIDEVICE\fR is not an enclosure and exit without doing any harm.
.TP
\fB\-p\fR, \fB\-\-page\fR=\fIPG\fR
where \fIPG\fR is a dpage abbreviation or code (a number). If \fIPG\fR
starts with a digit it is assumed to be in decimal unless prefixed by
0x for hex. Valid range is 0 to 255 (0x0 to 0xff) inclusive. Default is
dpage 'sdp' which is page_code 0 (i.e. "Supported Diagnostic Pages") if
no other options are given.
.br
Page code 0xff or abbreviation "all" is not a real dpage (as the highest real
dpage is 0x3f) but instead causes all SES dpages whose page code is 0x2f or
less to be output. This can be used with either the \fI\-HHHH\fR or \fI\-rr\fR
to send either hexadecimal ASCII or binary respectively to stdout. If an error
is detected fetching or decoding a diagnostic page it is noted, the rest of
the pages are processed then the deferred error is reported in the exit
status. If the \fI\-\-warn\fR option is also given then \fI\-\-page=all\fR
will exit immediately when an error is detected.
.br
To list the available dpage abbreviations give "xxx" for \fIPG\fR; the same
information can also be found with the \fI\-\-enumerate\fR option.
.TP
\fB\-q\fR, \fB\-\-quiet\fR
this suppresses the number of warnings and messages output. The exit status
of the utility is unaffected by this option.
.TP
\fB\-r\fR, \fB\-\-raw\fR
outputs the chosen status dpage in ASCII hex in a format suitable for a
later invocation using the \fI\-\-data=\fR option. A dpage less its first
4 bytes (page code and length) is output. When used twice (e.g. \fI\-rr\fR)
the full dpage contents is output in binary to stdout.
.br
Note that the use of a single \fI\-\-raw\fR option is different from most
other utilities in the sg3_utils package.
.br
When \fI\-rr\fR is used together with the \fI\-\-data=\-\fR,
\fI\-\-data=@FN\fR, or \fI\-\-inhex=FN\fR then stdin or file FN is decoded as
a binary stream that continues to be read until an end of file (EOF). Once
that data is read then the internal raw option is cleared to 0 so the output
is not effected. So the \fI\-rr\fR option either changes how the input or
output is treated, but not both in a single invocation.
.TP
\fB\-R\fR, \fB\-\-readonly\fR
open the \fIDEVICE\fR read\-only (e.g. in Unix with the O_RDONLY flag).
The default is to open it read\-write.
.TP
\fB\-A\fR, \fB\-\-sas\-addr\fR=\fISA\fR
this is an indexing method for SAS end devices (e.g. SAS disks). The utility
will try to find the element or slot in the Additional Element Status dpage
whose SAS address matches \fISA\fR. For a SAS disk or tape that SAS address
is its target port identifier for the port connected to that element or slot.
Most SAS disks and tapes have two such target ports, usually numbered
consecutively.
.br
SATA devices in a SAS enclosure often receive "manufactured" target port
identifiers from a SAS expander; typically will have a SAS address close to,
but different from, the SAS address of the expander itself. Note that this
manufactured target port identifier is different from a SATA disk's WWN.
.br
\fISA\fR is a hex number that is up to 8 digits long. It may have a
leading '0x' or '0X' or a trailing 'h' or 'H'. This option is a medium level
indexing alternative to the low level \fI\-\-index=\fR options.
See the DESCRIPTOR NAME, DEVICE SLOT NUMBER AND SAS ADDRESS section below.
.TP
\fB\-S\fR, \fB\-\-set\fR=\fISTR\fR
Used to set an element field in the Enclosure Control or Threshold Out dpage.
Must be used together with an indexing option to specify which element is to
be changed. The Enclosure Control dpage is assumed if the \fI\-\-page=PG\fR
option is not given. See the STR FORMAT and CLEAR, GET, SET sections below.
.TP
\fB\-s\fR, \fB\-\-status\fR
will fetch dpage from the \fIDEVICE\fR via a SCSI RECEIVE DIAGNOSTIC RESULTS
command (or from \fI\-\-data=@FN\fR). In the absence of other options that
imply modifying a dpage (e.g.  \fI\-\-control\fR or \fI\-\-set=STR\fR) then
\fI\-\-status\fR is assumed, except when the \fI\-\-data=\fR option is given.
When the \fI\-\-data=\fR option is given there is no default action: either
the \fI\-\-control\fR or this option must be given to distinguish between
the two different ways that data will be treated.
.TP
\fB\-v\fR, \fB\-\-verbose\fR
increase the level of verbosity. For example when this option is given four
times (in which case the short form is more convenient: '\-vvvv') then if
the internal join array has been generated then it is output to stderr in
a form suitable for debugging.
.TP
\fB\-V\fR, \fB\-\-version\fR
print the version string and then exit.
.TP
\fB\-w\fR, \fB\-\-warn\fR
warn about certain irregularities with warnings sent to stderr. The join is a
complex operation that requires fields from several dpages to be synchronized.
The quality of SES devices vary and to be fair, the descriptions from T10
drafts and standards have been tweaked several times (see the EIIOE field) in
order to clear up confusion.
.br
This option will cause fetching all dpages with the \fI\-\-page=all\fR option
to exit immediately when an error is detected.
.SH INDEXES
An enclosure can have information about its disk and tape drives plus other
supporting components like power supplies spread across several dpages.
Addressing a specific element (overall or individual) within a dpage is
complicated. This section describes low level indexing (i.e. choosing a single
element (or a group of related elements) from a large number of elements). If
available, the medium level indexing described in the following
section (DESCRIPTOR NAME, DEVICE SLOT NUMBER AND SAS ADDRESS) might be simpler
to use.
.PP
The Configuration dpage is key to low level indexing: it contains a list
of "type headers", each of which contains an Element type (e.g. Array
Device Slot), a Subenclosure identifier (0 for the primary enclosure) and
a "Number of possible elements". Corresponding to each type header, the
Enclosure Status dpage has one "overall" element plus "Number of possible
elements" individual elements all of which have the given Element type. For
some Element types the "Number of possible elements" will be 0 so the
Enclosure Status dpage has only one "overall" element corresponding to that
type header. The Element Descriptor dpage and the Threshold (In and Out)
dpages follow a similar pattern as the Enclosure Status dpage.
.PP
The numeric index corresponding to the overall element is "\-1". If the
Configuration dpage indicates a particular element type has "n" elements
then its indexes range from \-1 to n\-1 .
.PP
The Additional Element Status dpage is a bit more complicated. It has
entries for "Number of possible elements" of certain Element types. It
does not have entries corresponding to the "overall" elements. To make
the correspondence a little clearer each descriptor in this dpage optionally
contains an "Element Index Present" (EIP) indicator. If EIP is set then each
element's "Element Index" field refers to the position of the corresponding
element in the Enclosure Status dpage.
.PP
Addressing a single overall element or a single individual element is done
with two indexes: TI and II. TI=0 corresponds to the first type header entry
which must be a Device Slot or Array Device Slot Element type (according to
the SES\-2 standard). To address the corresponding overall instance, II is
set to \-1, otherwise II can be set to the individual instance index. As an
alternative to the type header index (TI), an Element type
abbreviation (A) (e.g. "ps" for Power Supply Element type) optionally followed
by a number (e.g. "ps" refers to the first Power Supply Element type; "ps1"
refers to the second) can be given.
.PP
One of two command lines variants can be used to specify indexes:
\fI\-\-index=TIA,II\fR where \fITIA\fR is either an type header index (TI)
or an Element type abbreviation (A) (e.g. "ps" or "ps1"). \fIII\fR is either
an individual index or "\-1" to specify the overall element. The second
variant is \fI\-\-index=IIA\fR where \fIIIA\fR is either an individual
index (II) or an Element type abbreviation (A). When \fIIIA\fR is an
individual index then the option is equivalent to \fI\-\-index=0,II\fR. When
\fIIIA\fR is an Element type abbreviation then the option is equivalent to
\fI\-\-index=A,\-1\fR.
.PP
Wherever an individual index is applicable, it can be replaced by an
individual index range. It has the form: <first_ii>:<last_ii>. For
example: '3:5' will select individual indexes 3, 4 and 5 . Note that the
range \-1:255 represents all possible elements of an element type and is not
an error, only those element that exist will be selected. Previously '\-' was
used as an index range separator but that leads to awkward syntax like
\-1\-1 for indexes: \-1 (overall element), 0 and 1 (individual elements).
.PP
To cope with vendor specific Element types (whose type codes should be in
the range 128 to 255) the Element type code can be given as a number with
a leading underscore. For example these are equivalent: \fI\-\-index=arr\fR
and \fI\-\-index=_23\fR since the Array Device Slot Element type code is 23.
Also \fI\-\-index=ps1\fR and \fI\-\-index=_2_1\fR are equivalent.
.PP
Another example: if the first type header in the Configuration dpage has
has Array Device Slot Element type then \fI\-\-index=0,\-1\fR is
equivalent to \fI\-\-index=arr\fR. Also \fI\-\-index=arr,3\fR is equivalent
to \fI\-\-index=3\fR.
.PP
The \fI\-\-index=\fR option is used to reduce the amount of output (e.g. only
showing the element associated with the second 12 volt power supply). It may
also be used together with with the \fI\-\-clear=STR\fR, \fI\-\-get=STR\fR
and \fI\-\-set=STR\fR options which are described in the STR section below.
.SH DESCRIPTOR NAME, DEVICE SLOT NUMBER AND SAS ADDRESS
The three options: \fI\-\-descriptor=DES\fR, \fI\-\-dev\-slot\-num=SN\fR and
\fI\-\-sas\-addr=SA\fR allow medium level indexing, as an alternative to the
low level \fI\-\-index=\fR option. Only one of the three options can be used
in an invocation. When either of these three option is used a join operation
is performed (but not displayed) before element selection takes place.
.PP
These medium level indexing options need support from the SES device and that
support is optional. For example the \fI\-\-descriptor=DES\fR needs the
Element Descriptor dpage provided by the SES device however that is optional.
Also the provided descriptor names need to be useful, and having descriptor
names which are all "0" is not very useful. Also some elements (e.g. overall
elements) may not have descriptor names.
.PP
These medium level indexing options can be used to reduce the amount of
output (e.g. only showing the elements related to device slot number 3).
They may also be used together with with the \fI\-\-clear=STR\fR,
\fI\-\-get=STR\fR and \fI\-\-set=STR\fR options which are described in the
following section. Note that even if a field can be set (e.g. "do not
remove" (dnr)) and that field can be read back with \fI\-\-get=STR\fR
confirming that change, the disk array may still ignore it (e.g. because it
does not have the mechanism to lock the disk drawer).
.SH STR FORMAT
The \fISTR\fR operands of the \fI\-\-clear=STR\fR, \fI\-\-get=STR\fR and
\fI\-\-set=STR\fR options all have the same structure. There are two forms:
.PP
      <acronym>[=<value>]
      <start_byte>:<start_bit>[:<num_bits>][=<value>]
.PP
The <acronym> is one of a list of common fields (e.g. "ident" and "fault")
that the utility converts internally into the second form. The <start_byte>
is usually in the range 0 to 3, the <start_bit> must be in the range 0 to
7 and the <num_bits> must be in the range 1 to 64 (default 1). The
number of bits are read in the left to right sense of the element tables
shown in the various SES draft documents. For example the 8 bits of
byte 2 would be represented as 2:7:8 with the most significant bit being
2:7 and the least significant bit being 2:0 .
.PP
The <value> is optional but is ignored if provided to \fI\-\-get=STR\fR.
For \fI\-\-set=STR\fR the default <value> is 1 while for \fI\-\-clear=STR\fR
the default value is 0 . <value> is assumed to be decimal, hexadecimal
values can be given in the normal fashion.
.PP
The supported list of <acronym>s can be viewed by using the
\fI\-\-enumerate\fR option twice (or "\-ee").
.SH CLEAR, GET, SET
The \fI\-\-clear=STR\fR, \fI\-\-get=STR\fR and \fI\-\-set=STR\fR options can
be used up to 8 times in the same invocation. Any <acronym>s used in the
\fISTR\fR operands must refer to the same dpage.
.PP
When multiple of these options are used (maximum: 8), they are applied in the
order in which they appear on the command line. So if options contradict each
other, the last one appearing on the command line will be enforced. When
there are multiple \fI\-\-clear=STR\fR and \fI\-\-set=STR\fR options, then
the dpage they refer to is only written after the last one.
.SH DATA SUPPLIED
This section describes the two scenarios that can occur when the
\fI\-\-data=\fR option is given. These scenarios are the same irrespective
of whether the argument to the \fI\-\-data=\fR option is a string of
hex bytes on the command line, stdin (indicated by \fI\-\-data=\-\fR) or
names a file (e.g. \fI\-\-data=@thresh_in_dpage.hex\fR).
.PP
The first scenario is flagged by the \fI\-\-control\fR option. It uses the
supplied data to build a 'control' dpage that will be sent to the
\fIDEVICE\fR using the SCSI SCSI SEND DIAGNOSTIC command. The supplied dpage
data should not include its first 4 bytes. Those 4 bytes are added by this
utility using the \fI\-\-page=PG\fR option with \fIPG\fR placed at byte
offset 0). If needed, the \fI\-\-byte1=B1\fR option sets byte offset 1,
else 0 is placed in that position. The number of bytes decoded from the data
provided (i.e. its length) goes into byte offsets 2 and 3.
.PP
The second scenario is flagged by the \fI\-\-status\fR option (or the absence
of the \fI\-\-control\fR option). It decodes the supplied data assuming that
it represents the response to one or more SCSI RECEIVE DIAGNOSTIC RESULTS
commands. Those responses have typically been captured from some earlier
invocation(s) of this utility. Those earlier invocations could use
the '\-HHH' or '\-HHHH' option and file redirection to capture that
response (or responses) in hexadecimal. The supplied dpage response data is
decoded according to the other command line options. For example the
\fI\-\-join\fR option could be given and that would require the data from
multiple dpages typically:  Configuration, Enclosure status, Element
descriptor and Additional element status dpages. If in doubt use
\fI\-\-page=all\fR in the capture phase; having more dpages than needed
is not a problem.
.PP
By default the user supplied data is assumed to be ASCII hexadecimal in
lines that don't exceed 512 characters. Anything on a line from and
including a hash mark ('#') to the end of line is ignored. An end of
line can be a LF or CR,LF and blank lines are ignored. Each separated
pair (or single) hexadecimal digits represent a byte (and neither a
leading '0x' nor a trailing 'h' should be given). Separators are either
space, tab, comma or end of line.
.PP
Alternatively binary can be used and this is flagged by the '\-rr' option.
The \fI\-\-data=H,H...\fR form cannot use binary values for the 'H's, only
ASCII hexadecimal. The other two forms (\fI\-\-data=\-\fR and
\fI\-\-data=@FN\fR) may contain binary data. Note that when the '\-rr'
option is used with \fI\-\-data=@FN\fR that it only changes the
interpretation of the input data, it does not change the decoding and output
representation.
.SH CHANGING STATE
This utility has various techniques for changing the state of a SES device.
As noted above this is typically a read\-modify\-write type operation.
Most modifiable dpages have a "status" (or "in") page that can be read, and
a corresponding "control" (or "out") dpage that can be written back to change
the state of the enclosure.
.PP
The lower level technique provided by this utility involves outputting
a "status" dpage in hex with \fI\-\-raw\fR. Then a text editor can be used
to edit the hex (note: to change an Enclosure Control descriptor the SELECT
bit needs to be set). Next the control dpage data can fed back with the
\fI\-\-data=H,H...\fR option together with the \fI\-\-control\fR option;
the \fI\-\-byte1=B1\fR option may need to be given as well.
.PP
Changes to the Enclosure Control dpage (and the Threshold Out dpage) can be
done at a higher level. This involves choosing a dpage (the default in this
case is the Enclosure Control dpage). Next choose an individual or overall
element index (or name it with its Element Descriptor string). Then give
the element's name (e.g. "ident" for RQST IDENT) or its position within that
element (e.g. in an Array Device Slot Control element RQST IDENT is byte 2,
bit 1 and 1 bit long ("2:1:1")). Finally a value can be given, if not the
value for \fI\-\-set=STR\fR defaults to 1 and for \fI\-\-clear=STR\fR
defaults to 0.
.SH SETTING SUBENCLOSURE NICKNAME
The format of the Subenclosure Nickname control dpage is different from its
corresponding status dpage. The status dpage reports all Subenclosure
Nicknames (and Subenclosure identifier 0 is the main enclosure) while the
control dpage allows only one of them to be changed. Therefore using the
\fB\-\-data\fR option technique to change a Subenclosure nickname is
difficult (but still possible).
.PP
To simplify changing a Subenclosure nickname the \fI\-\-nickname=SEN\fR and
\fI\-\-nickid=SEID\fR options have been added. If the \fISEN\fR string
contains spaces or other punctuation, it should be quoted: surrounded by
single or double quotes (or the offending characters escaped). If the
\fI\-\-nickid=SEID\fR is not given then a Subenclosure identifier of 0 is
assumed. As a guard the \fI\-\-control\fR option must also be given. If
the \fI\-\-page=PG\fR option is not given then \fI\-\-page=snic\fR is
assumed.
.PP
When \fI\-\-nickname=SEN\fR is given then the Subenclosure Nickname Status
dpage is read to obtain the Generation Code field. That Generation Code
together with no more than 32 bytes from the Nickname (\fISEN\fR) and the
Subenclosure Identifier (\fISEID\fR) are written to the Subenclosure Nickname
Control dpage.
.PP
There is an example of changing a nickname in the EXAMPLES section below.
.SH NVME ENCLOSURES
Support has been added to sg_ses (actually, its underlying library) for
NVMe (also known as NVM Express) Enclosures. It can be considered
experimental in sg3_utils package version 1.43 and sg_ses version 2.34 .
.PP
This support is based on a decision by NVME\-MI (Management Interface)
developers to support the SES\-3 standard. This was facilitated by adding
NVME\-MI SES Send and SES Receive commands that tunnel dpage contents as
used by SES.
.SH JSON INFORMATION
The approach taken with JSON output (i.e. when the \fI\-\-json[=JO]\fR option
is given) is to output diagnostic page information unless the \fI\-\-join\fR
option is given. A problem specific to SES is that many diagnostic pages
depend on other diagnostic pages (e.g. decoding the Enclosure Status and the
Element Descriptor dpages both depend on the Configuration dpage).
.PP
When the \fI\-\-json[=JO]\fR and \fI\-\-page=PG\fR options are used in the
same invocation, then if \fIPG\fR has any dependencies on other diagnostic
pages, then those other pages are fetched. For example the Element Descriptor
dpage depends on the Configuration dpage. In some cases (e.g. dpages
misconfigured or in the process of being changed) it may be useful to decode
whatever is possible, without fetching other dpages. The \fI\-\-inner\-hex\fR
option may be used for this. Some dpages (e.g.  Enclosure Status dpage)
cannot be decoded at all, without fetching the Configuration dpage, so each 4
byte element will be output in hex. In the case of the Element Descriptor
dpage, the descriptors may be output in ASCII and are when the
\fI\-\-inner\-hex\fR option is given once. If the \fI\-\-inner\-hex\fR
option is given twice, then each descriptor will be output in hex.
.PP
When the \fI\-\-json[=JO]\fR and \fI\-\-page=PG\fR options are used in the
same invocation, then the top level object name is the name of \fIPG\fR in
snake notation. This includes the "_diagnostic_page" suffix.
.PP
When the \fI\-\-json[=JO]\fR and \fI\-\-join\fR options are used in the same
invocation (and the \fI\-\-page=PG\fR option is _not_ given), then the top
level object name is "join_of_diagnostic_pages" which contain a (JSON) array
named "element_list". Each element in that array starts with an "element_type"
field followed by "descriptor" and "element_number" fields. The "descriptor"
field's value is a string. All elements with the same "element_type" are
grouped together starting with the "overall_element" first.
The "overall_element" has an "element_number" value of -1. Individual
elements of the same "element_type" are in the following "element_list" array
elements start with an "element_number" value of 0. After
the "element_number" field there is a "overall" field with an integer value
of 0 (for an "individual" element) or a value of 1 (for "overall" element).
To reinforce that point there is a "individual" field with a boolean value
of true (for an "individual" element) or false. Next there is an object
named "status_descriptor" that contains the corresponding "Enclosure
Status" dpage's Enclosure status element. As required, the corresponding
Additional element status, Element descriptor by type element, and
Threshold status descriptors may also appear.
.PP
The plain text output (which is output by default) tends to trim output
when a line of element values are all 0. On the other hand when JSON output
is chosen, all fields, that meet the requirements of the command line
options, are output.
.SH NOTES
This utility can be used to fetch arbitrary (i.e. non SES) dpages (using
the SCSI READ DIAGNOSTIC command). To this end the \fI\-\-page=PG\fR and
\fI\-\-hex\fR options would be appropriate. Non\-SES dpages can be sent to
a device with the sg_senddiag utility.
.PP
The most troublesome part of the join operation is associating Additional
Element Status descriptors correctly. At least one SES device vendor has
misinterpreted the SES\-2 standard, specifically with its "element index"
field interpretation. The code in this utility interprets the "element
index" field as per the SES\-2 standard and if that yields an inappropriate
Element type, adjusts its indexing to follow that vendor's
misinterpretation. The SES\-3 drafts have introduced the EIIOE (Element
Index Includes Overall Elements) bit which later became a 2 bit field to
resolve this ambiguity. See the \fI\-\-eiioe=A_F\fR option.
.PP
In draft SES\-3 revision 5 the "Door Lock" element name was changed to
the "Door" (and an OPEN field was added to the status element). As a
consequence the former 'dl' element type abbreviation has been changed
to 'do'.
.PP
Some RAID controllers hide SES device nodes from the host Operating System.
It has been reported that some MegaRAID controllers do this and the
following command is needed to expose them:
.PP
   perccli /cx set backplane expose=<on/off>
.PP
where perccli is Dell's version of BroadCom's (LSI) storcli utility.
.PP
There is a related command set called SAF\-TE (SCSI attached fault\-tolerant
enclosure) for enclosure (including RAID) status and control. SCSI devices
that support SAF\-TE report "Processor" peripheral device type (0x3) in their
INQUIRY response. See the sg_safte utility in this package or the
safte\-monitor utility on the Internet.
.PP
The internal join array is statically allocated and its size is controlled
by the MX_JOIN_ROWS define. Its current value is 520.
.SH EXAMPLES
Examples can also be found at https://sg.danny.cz/sg/sg_ses.html
.PP
The following examples use Linux device names. For suitable device names
in other supported Operating Systems see the sg3_utils(8) man page.
.PP
To view the supported dpages:
.PP
   sg_ses /dev/bsg/6:0:2:0
.PP
To view the Configuration Diagnostic dpage:
.PP
   sg_ses \-\-page=cf /dev/bsg/6:0:2:0
.PP
To view the Enclosure Status dpage:
.PP
   sg_ses \-\-page=es /dev/bsg/6:0:2:0
.PP
To get the (attached) SAS address of that device (which is held in the
Additional Element Sense dpage (dpage 10)) printed on hex:
.PP
   sg_ses \-p aes \-D ArrayDevice07 \-G at_sas_addr \-H /dev/sg3
.PP
To collate the information in the Enclosure Status, Element Descriptor
and Additional Element Status dpages the \fI\-\-join\fR option can be used:
.PP
   sg_ses \-\-join /dev/sg3
.PP
This will produce a lot of output. To filter out lines that don't contain
much information add the \fI\-\-filter\fR option:
.PP
   sg_ses \-\-join \-\-filter /dev/sg3
.PP
Fields in the various elements of the Enclosure Control and Threshold dpages
can be changed with the \fI\-\-clear=STR\fR and \fI\-\-set=STR\fR
options. [All modifiable dpages can be changed with the \fI\-\-raw\fR and
\fI\-\-data=H,H...\fR options.] The following example looks at making
the "ident" LED (also called "locate") flash on "ArrayDevice07" which is a
disk (or more precisely the carrier drawer the disk is in):
.PP
   sg_ses \-\-index=7 \-\-set=2:1:1 /dev/sg3
.PP
In the above invocation, the \-\-set= option implies \-\-control so the
latter does not need to be given. The same applies to \-\-clear=. On the
other hand the \-\-get= option implies \-\-status .
.br
If the Element Descriptor diagnostic dpage shows that "ArrayDevice07" is
the descriptor name associated with element index 7 then this invocation
is equivalent to the previous one:
.PP
   sg_ses \-\-descriptor=ArrayDevice07 \-\-set=2:1:1 /dev/sg3
.PP
Further the byte 2, bit 1 (for 1 bit) field in the Array Device Slot Control
element is RQST IDENT for asking a disk carrier to flash a LED so it can
be located. In this case "ident" (or "locate") is accepted as an acronym
for that field:
.PP
   sg_ses \-\-descriptor=ArrayDevice07 \-\-set=ident /dev/sg3
.PP
To stop that LED flashing:
.PP
   sg_ses \-\-dev\-slot\-num=7 \-\-clear=ident /dev/sg3
.PP
The above assumes the descriptor name 'ArrayDevice07' corresponds to device
slot number 7.
.PP
Now for an example of a more general but lower level technique for changing
a modifiable diagnostic dpage. The String (In and Out) diagnostics dpage is
relatively simple (compared with the Enclosure Status/Control dpage). However
the use of this lower level technique is awkward involving three steps: read,
modify then write. First check the current String (In) dpage contents:
.PP
   sg_ses \-\-page=str /dev/bsg/6:0:2:0
.PP
Now the "read" step. The following command will send the contents of the
String dpage (from byte 4 onwards) to stdout. The output will be in ASCII
hex with pairs of hex digits representing a byte, 16 pairs per line,
space separated. The redirection puts stdout in a file called "t":
.PP
   sg_ses \-\-page=str \-\-raw /dev/bsg/6:0:2:0 > t
.PP
Then with the aid of the SES\-3 document (in revision 3: section 6.1.6)
use your favourite editor to change t. The changes can be sent to the
device with:
.PP
   sg_ses \-\-page=str \-\-control \-\-data=\- /dev/bsg/6:0:2:0 < t
.PP
If the above is successful, the String dpage should have been changed. To
check try:
.PP
   sg_ses \-\-page=str /dev/bsg/6:0:2:0
.PP
To change the nickname on the main enclosure:
.PP
   sg_ses \-\-nickname='1st enclosure' \-\-control /dev/bsg/6:0:2:0
.PP
To capture the whole state of an enclosure (from a SES perspective) for
later analysis, this can be done:
.PP
   sg_ses \-\-page=all \-HHHH /dev/sg5 > enc_sg5_all.hex
.PP
Note that if there are errors or warnings they will be sent to stderr so
they will appear on the command line (since only stdout is redirected).
A text editor could be used to inspect enc_sg5_all.hex . If all looks in
order at some later time, potentially on a different machine where
enc_sg5_all.hex has been copied, a "join" could be done. Note that join
reflects the state of the enclosure when the capture was done.
.PP
   sg_ses \-\-data=@enc_sg5_all.hex \-\-status \-\-join
.PP
The above invocation can also be expressed as:
   sg_ses \-\-inhex=enc_sg5_all.hex \-\-join
.PP
The \-\-join option implies \-\-status .
.SH EXIT STATUS
The exit status of sg_ses is 0 when it is successful. Otherwise see
the sg3_utils(8) man page.
.SH AUTHORS
Written by Douglas Gilbert.
.SH "REPORTING BUGS"
Report bugs to <dgilbert at interlog dot com>.
.SH COPYRIGHT
Copyright \(co 2004\-2023 Douglas Gilbert
.br
This software is distributed under a BSD\-2\-Clause license. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
.SH "SEE ALSO"
.B sg_inq, sg_safte, sg_senddiag, sg_ses_microcode, sg3_utils (sg3_utils);
.B safte\-monitor (Internet)
